淺談 ASP.NET Core 中的環境名稱設定與應用

TLDR

• ASP.NET Core 透過 ASPNETCORE_ENVIRONMENT 變數區分環境，預設包含 Development、Staging 與 Production。
• 設定檔載入機制為「後載入覆蓋前載入」，系統會自動載入 appsettings.json 後再載入 appsettings.{EnvironmentName}.json。
• 避免在 Program.cs 中手動重複載入設定檔，以免覆蓋掉環境專屬的設定。
• launchSettings.json 僅適用於本機開發，正式環境需透過 IIS (web.config) 或 Dockerfile 設定環境變數。
• 執行階段可透過注入 IWebHostEnvironment 並使用 IsDevelopment()、IsStaging() 或 IsEnvironment() 等擴充方法判斷當前環境。

環境名稱與組態載入機制

在 ASP.NET Core 中，環境變數 EnvironmentName 用於區分不同執行環境。系統預設提供 Development、Staging 與 Production 三種值。

與舊版 .NET Framework 的 Web.config 轉換機制不同，ASP.NET Core 採用 appsettings.json 的覆蓋邏輯。當執行 WebApplication.CreateBuilder(args) 時，系統會自動依序載入設定：

builder.ConfigureAppConfiguration((hostingContext, config) => {
    IHostEnvironment env = hostingContext.HostingEnvironment;
    bool reloadOnChange = GetReloadConfigOnChangeValue(hostingContext);

    config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: reloadOnChange)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: reloadOnChange);
    // ...
})

WARNING

什麼情況下會遇到這個問題： 在 Program.cs 中手動重複載入設定檔。 由於 ASP.NET Core 內部已自動處理 appsettings.json 與 appsettings.{環境}.json 的載入，若開發者在程式中手動再次載入這些檔案，可能會導致設定被意外覆蓋，造成環境變數失效。

設定環境變數的方法

本機開發環境

開發者可透過 Properties\launchSettings.json 設定本機環境，此設定會覆蓋全域環境變數。

{
  "profiles": {
    "Sample": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

IIS 發佈環境

若使用 Visual Studio 發佈，需在發佈設定檔 (Publish Profile) 的 XML 中加入 <EnvironmentName> 標籤。發佈後，系統會自動在 web.config 中產生對應的環境變數設定：

<aspNetCore processPath="dotnet" arguments=".\YourApp.dll">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Staging" />
  </environmentVariables>
</aspNetCore>

TIP

什麼情況下會遇到這個問題： 嘗試排除多餘的設定檔。 在 ASP.NET Core 中，舊版 web.config 的 <ExcludeFilesFromDeployment> 設定已失效，無法透過此方式排除多餘的 appsettings.{環境}.json 檔案。

Docker 容器環境

在 Dockerfile 中，可直接使用 ENV 指令設定環境變數：

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
ENV ASPNETCORE_ENVIRONMENT=Staging

執行階段判斷環境

若需在程式碼中根據環境執行不同邏輯，可注入 IWebHostEnvironment 介面。

• 使用內建擴充方法：IsDevelopment()、IsStaging()、IsProduction()。
• 使用自定義環境名稱：IsEnvironment("YourCustomName")。

異動歷程

• 2024-07-12 初版文件建立。